USER-DEFINED FUNCTIONS IN SMATH STUDIO
[ rev.08 | 2016.12.08 | SS 0.98.6179 ]
Inline functions
To define a function, type function's name and open a parenthesis "(", write the argument name, move on the right of the closing parenthesis and then type the define operator ":".
[1.1]
<- type f and look at the dynamic assistance, you will find the functiom name and his content.
type = to evaluate numerically
type CTRL+. to evaluate symbolically
evaluation can be changed by context menu: 1. right click on the math region 2. Optimization > [Symbolic/Numeric/None]
Like variables, functions are case sensitive, hence f(x)≠F(x)
[1.2]
It is possible to define several functions with the same name, if they have a different number of arguments.
[1.3]
<- f(x) is still defined; if you look at the dynamic assistance, 2 items are available now, f(1) and f(2). The number shows the arguments required by each function, whereas the name without numbers is used when there is just one function (see [1.1])
It is possible to define again the function
[1.4]
Evaluable things such math regions are ordered in the canvas from left to right and then from top to bottom, with reference to the top-left corner of the region.
In SS a valid variable name cannot start with a number; it cannot contains whitespaces nor the character used as argument separator in functions, as well as @ and the math symbols: ()[]{}+-/*=:≡<>≤≥≠¬&|¤± ...
When you define a function, argument's name can be only: a variable name or a function; units and empty operand can be used only as placeholders.
[1.5]
[A]
<- the name of an argument cannot be a number
lastError contains the last error detected up to the point where it is used
if your intent is to define the value of a function in a point, use an if statement, booleans or other functions
[B]
<- the variable name can contain numbers (not as 1st character)
[C]
<- any non-number character is allowed as first character
[D]
<- # is the character of the empty placeholder; to use it as 1st character you have to type at least the one that will be the 2nd character, move back the cursor, and then you can type # in front of it
[E]
<- dummy argument (argument not used in the function - will be discussed later in [3.14])
[F]
<- dummy argument
[G]
<- a function is a valid argument (will be further discussed from [3.10] to [3.13])
You can access variables from the canvas (not passed by the arguments), defined or even not yet defined (from left to right and from top to bottom, see [1.4]).
[1.6]
<- hold the mouse over the function to see how "a" and "b" are stored; you can do the same from the dynamic assistance
[A]
[B]
<- if a variable is not yet defined when you define the function, it is kept as symbolical link (the name is stored); hence if afterwards you change the value of the variable, the function will returns a different result.
[C]
<- if a variable is already defined when you define the function, the value is stored; hence if afterwards you change the value of the variable, the function will returns always the same result.
[1.7]
<- this principle applies to anything in the right hand side of assignments, even functions
[A]
<- the value of F(x) was stored as it was at f(x) definition, thus when you change F(x) the new value is NOT used in f(x)
[B]
[C]
<- G(x) wasn't defined at f(x) definition, thus his name is stored and when you change it the new content is used in f(x)
You can use vectorize() to extend scalar logic to matrices/vectors elements avoiding the use of loops; this can be done applying vectorize on you function or inside your function.
[SMath Studio ≥ 0.98]
[1.8]
<- the scalar logic is extended to any element of the matrix, because requested by vectorize(...)
[1.9]
<- the scalar logic is always extended to any matrix's element
Dependent variables
Like in paper-math you may want to have a function without explicit arguments:
[2.1]
[A]
[B]
[C]
<- even if x is defined at the execution, y keeps the symbolical link (look at the dynamic assistance and [1.5][B])
Like in functions, it is possible to use defined/undefined variables from the canvas.
[2.2]
<- hold the mouse over the variable to see how "b" and "c" are managed: c was undefined and his name is stored, b was defined and his value is replaced and stored.
[A]
[B]
[2.3]
<- hold the mouse over the definition of x
[A]
d wasn't defined before x's definition => his name is stored => defining d with different values, you obtain different results when you evaluate again x
[B]
[C]
[D]
b was defined before x's definition => his value (5) is stored in x => doesn't matter if you define b in another way
[E]
G(z) was defined before x's definition => his value (3*z) is stored in x => doesn't matter if you define G(z) in another way
To make complex tasks, it is possible to use the line() function in the Right Hand Side. This function and his block of statements applied right after the assignment operator is called Procedure. A procedure acts like a logical function (is fully evaluated anytime is called). line() is available even in the "Programming" toolbox on the right side of the program.
Type an "argument separator" character to add a placeholder in the line.
[2.4]
<- hold the mouse over the region to see how the procedure is stored; as you can see the whole logic is kept in memory, no replacements are made
<- The last placeholder is used to output the result
[A]
<- if the logic in the procedure doesn't depends from outer variables, you can speed-up calculations inside loops by evaluating it at once before his repetitive use, assigning the variable to another one (even with the same name)
[B]
What does it means here "doesn't depends from outer variables"? When the procedure will be evaluated if a variable is not defined inside the procedure but is available in the parent level, his value will be used.
[2.5]
<- even if it is available in the canvas, "b" is an unknown inside the procedure (not defined anywhere locally, is a "local unknown")
[A]
<- 3+4=7; "b" is used with his canvas' value
<- the canvas value of "a" is still the same
[B]
<- 3+7=10; changing the value of b changes even the output value of x
[C]
<- store the value of x inside a new variable named x
<- the dependancy from b is gone (see [2.4])
What if the local unknown is unknown even in the parent level?
[2.6]
<- the local unknow is exposed to the canvas
<- in this case is even possible to partially evaluate x and store it in a new variable (even "x") to speed up further calculations; when some numerical function acts on the unknown such evaluation it might be not possible and the new variable will point the original (y=x)
<- as for [2.5], since "w" wasn't defined locally, the current value will be used
Now let's go deeper; we know that a canvas value may be assigned (if available) to a local unknow when the procedure is being evaluation, but in what point of our function the canvas value is applied to our unknown when executed?
[2.7]
<- "b" is unknown in the procedure
<- from this point on, "b" is known, his local value will be used in following assignments
[A]
<- (2+3)+20=25
<- the canvas value of "b" is still the same
[B]
<- (100+3)+20=123
If line() is no more applied right after the definition operator, becomes a passive wrapper for his content; anything will be immediatly evaluated
[2.8]
<- notice the + before the line(); a parenthesis will do the same (or sys(), etc...)
<- last placeholder is still the output value
<- assignments made inside line() are available on the canvas, as well as "x"
In a procedure you can rename a variable at once using the F8 key.
[2.9]
<- move the cursor above a variable (i.e. a); you should see all the occourrences of that item light-grayed
press the F8 key of your keyboard, aa cursor will appears in each of them
navigate with the keyboard arrows, type the new name, delete unwanted characters
use the escape key to go back to the normal mode (the same can be addressed with a mouse click)
Programming functions
Procedures can be used even to to make complex tasks in functions:
[3.1]
<- x is an argument of f
<- The last placeholder is used to output values
Arguments in programming functions are passed by reference, this means that an input variable can be modified from inside the function when you use the assignment operator (:=) to that variable inside the function
[3.2]
<- assignment operator applied to an input argument (x:=x+1)
[A]
<- result of the function
<- Pass by reference side effect
[B]
Note that the sintax is very compact
<- result of the function after the loop
<- Pass by reference side effect
The loop:
1st iteration ->
in the canvas
a:=1
in the function
since assignment is used on x ->
2nd iteration ->
in the canvas
a:=2
in the function
since assignment is used on x ->
and so on ...
[C]
<- result of the function is also the input variable
<- Pass by reference side effect overridden by the assignment on the canvas (because is the last executed)
The loop:
1st iteration ->
in the canvas
a:=1
in the function
since assignment is used on x ->
since the result is assigned to a ->
2nd iteration ->
in the canvas
a:=4
in the function
since assignment is used on x ->
since the result is assigned to a ->
a=25 >= 10 ->
[END OF THE LOOP]
A variable not defined in the canvas can be set in the canvas from inside the function, providing this variable is used as function's argument and a value assigned to it in the function
[3.3]
<- result of the function
<- Pass by reference side effect
If you expect to use the input variable as target of the calculations inside the function and you want to avoid side effects, you have to transfer the value to another variable and use the latest
[3.4]
<- No side effects (no assignment used on the function arguments)
Like for simple procedures, on evaluation "local unknowns" can get their value from the parent level (see [2.5])
[3.5]
<- c is an unknown in the function (not defined locally)
[A]
<- symbolically the output should be f(2)=2+3*c c exists in the canvas -> f(2)=2+3*3=11
[B]
<- symbolically the output should be f(2)=2+3*c c exists in the canvas -> f(2)=2+3*4=14
[3.6]
<- here k is unknown in the function => stored as name
<- from this point k is known in the function (local variable)
[A]
<- 2+3*5+5=22
<- no side effects
The use of local unknowns (or better "unassigned local variables") might lead you to unwanted results in some circustances.
One typical case is using features like "dynamic arrays" of matrices/systems. This feature allow to assign elements' values without initializing the matrix/system. If the target matrix is not defined locally, a matrix from the canvas may be used either intentionally or unintentionally; if you need to avoid this behavior you have to define the variable before using it (see example below)
[3.7]
[A]
<- you didn't notice differences
[B]
<- in f(x), M from canvas is used as template
[C]
Another typical case might happen working with symbolical functions. You might use a local unknown in the RHS of something, with the precise scope of being an unknown. If at the evaluation of the function a variable with the same name exists on the parent level, the result will be different from the one you planned (see below)
[3.8]
v1 stores 3+2*y1, because y1 doesn't exists anywhere;
v2 stores 13 (3+2*5), because y2=5 exists on the top level;
r1 stores 2 (expected value), because v1 contains the unknown y1;
r2 stores 0, because you are differentiating 13 (a constant);
r3 stores 2 (expected value), because the order of computation; first of all differentiation is made (calculation of the RHS), then the assignments looks to replace unknowns from RHS to store it in the variable LHS variable
This might become a huge problem on big worksheets or if you share the document and who will reuse your code doesn't realize it (maybe even you, after a long time).
What you can do to avoid this problem? - The strong way: initialize local variables (M:0, y2:line(y2,1,1), Clear(y1,y2)*, ...); - A less strong way: use "unique" names (x#, #x, _x, ...); Most important: always document your functions (right click -> show description);
* Clear(...) is a function from "Custom Functions" plug-in; basically you can do almost the same with the following syntax:
[3.9]
Can I pass a function as function argument? Yes, you can
[3.10]
<- note the uppercase X; because x is defined in the canvas, using test(x) I'd pass a number as function's argument
[3.11]
<- you can define the type of input function by defining the number of the arguments required for that function
[3.12]
<- 2-args function required as input
Can I pass a dependent variable as function argument? Yes, you can, providing that the function's argument is declared as a function with 0 arguments.
[3.13]
<- 0-args function required as input; note that here you have to know the names of the indipendent variables behind the dependent variable, if you want to define them from inside the function
<- 2*3*5=30
<- numbers are allowed as input
There is also the possibility to point out dummy arguments (dummy argument = something not used in the function)
[3.14]
<- you may use a variable and then leave it unused, however this point out immediatly that everything in the argument will be ignored in the function (you can use even an unit)
<- you still need to add a value to evaluate the function
Like for variables, it is possible to use functions already defined in the worksheet, or define locally other functions (nesting)
[3.15]
[3.16]
PROS of nesting functions: - you have g(y) right here; - you may keep a different function with the same name on the canvas, without interferences; - you may change the function locally several times (every time you need it) - if you don't need the nested function elsewhere, there's no need to have it on the canvas; CONS: - if g(y) is used elsewhere, you have to define it again; - every time you call f(x), time will be used to define again g(y); - local functions aren't available in the dynamic assistant; - (cosmetic) in some cases, the size of the function may become too big for the page layout;
The function itself can be used inside it to make recursive functions
[3.17]
WARNING
There's a know bug related to the control of recursive functions when they falls in infinite loops, that ends in an unrecoverable crash of the worksheet; check carefully the logic of your function and save the worksheet before the evaluation (disable auto calculation just-in-case)
<-- f.e. here it fails if you use a value < -1
As for inline functions, you can use vectorize() on your function or inside your function
[3.18]
[3.19]
Absolute definitions
This feature send the value to the top of the worksheet, making it available before the definition. To create an absolute definitions you have to type the TILDE (~) character before the name.
The value sent at the top of the worksheet will be available at the next recalculation. -> This features makes available values through worksheet's recalculations.
Pay attention to this, because actions on the worksheet may trigger partial evaluations of the worksheet, making results different from what you may think.
[4.1]
<- the variable is available above the definition
(press F9)
<- absolute definition -> value will be sent to the begin of the worksheet at the next recalculation (press F9)
<- the variable is updated by the worksheet flow
This feature is available also for functions
[4.2]
<- the function is available above the definition
(press F9)
<- absolute function
Here there are some examples of how something simple can be made in several ways. Namely we want to know Area, Perimeter and Centroid (refered to the bottom-left corner) of a rectangle, given his base and height.
<- chained definition; some alternatives:
↑NOTE: behavior of definitions inside matrices changed since SMath Studio 0.98
<- input database
output databases ↴
<- NOTE: functions inside procedures can be evaluated without assignment/evaluation operators